home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 013 / alint.arc / ALINT.DOC < prev    next >
Encoding:
Text File  |  1986-04-26  |  9.0 KB  |  249 lines
  1.                              alint 1.00   04/26/86
  2.  
  3.         Purpose
  4.         -------
  5.  
  6.         Alint is a miniature "lint" for assembler programmers.  It can
  7.         help you find data-type conflicts between modules of
  8.         multi-module assembler programs.
  9.  
  10.         For example, if you declare in Module A:
  11.  
  12.             public  a_var
  13.             a_var   dw ?
  14.  
  15.         and in Module B:
  16.  
  17.             extrn   a_var:byte
  18.  
  19.         you will find that neither the assembler nor the linker will
  20.         tell you that you have made a mistake.  If you were to code in
  21.         Module B:
  22.  
  23.             mov     a_var,0
  24.  
  25.         the assembler will clear only the low byte of the data word
  26.         'a_var'.  This kind of error can lead to obscure runtime
  27.         problems and is very difficult to debug.  Alint can detect this
  28.         type of error.
  29.  
  30.         Alint can optionally produce a cross-reference of all global
  31.         variables in a multi-module assembler program.
  32.  
  33.  
  34.         Use
  35.         ---
  36.  
  37.         To use alint in its default mode, simply type 'alint' at the
  38.         DOS prompt:
  39.  
  40.             C> alint<Enter>
  41.  
  42.         Alint will prompt for the names of the source files one by one;
  43.         enter the names of the assembler source files you want checked,
  44.         including drive and path if necessary.  If you do not include an
  45.         extension, alint will first look for the file as given; if it is
  46.         not found, it will then append the extension '.asm' and try
  47.         again.
  48.  
  49.         When you have entered all of the names, respond to the 'Source
  50.         file?' prompt by just hitting <Enter>.
  51.  
  52.         Alint will then read the source files one by one, and display a
  53.         list of errors when it is done.
  54.  
  55.         If you have many files to process, you may wish to instead
  56.         prepare a text file containing a list of the names of files to
  57.         be processed.  You can tell alint to read this "response file"
  58.         by placing its name on the command line:
  59.  
  60.             alint filelist.txt
  61.  
  62.         Use only one filename per line in your response file.  Any line
  63.         beginning with a semicolon will be ignored, thus allowing
  64.         comments.
  65.  
  66.  
  67.         Output format
  68.         -------------
  69.  
  70.         Alint will display certain information about each data item for
  71.         which any error was detected.  This information includes:
  72.  
  73.             1. The name of the item.
  74.             2. The name of the source file in which it is defined, along
  75.                with the data type (byte, word, dword, qword, tbyte) and
  76.                the line number in which it is defined.
  77.             3. The names of the source files in which the item is
  78.                referenced via EXTRN, along with the EXTRN line number
  79.                and data type.
  80.  
  81.         For example:
  82.  
  83.             MYVAR
  84.               Def dword   116 file1.asm
  85.               Ref word      5 file2.asm
  86.               Ref byte     14 file3.asm         *** TYPE MISMATCH ***
  87.  
  88.         The line marked DEF (for DEFinition) indicates that the variable
  89.         MYVAR is defined (and PUBLIC) in the source file FILE1.ASM.  It
  90.         is defined as a WORD quantity (either via DW or LABEL WORD) in
  91.         line 116 of FILE1.ASM.
  92.  
  93.         The first REF (for REFerence) line indicates that MYVAR is
  94.         referenced via an EXTRN statament in line 5 of the source file
  95.         FILE2.ASM, and that it is declared to be a WORD variable.
  96.  
  97.         The second REF line indicates that MYVAR is also referenced in
  98.         an EXTRN statament in line 14 of FILE3.ASM.  Here it is declared
  99.         to be a BYTE, and this is a type mismatch.
  100.  
  101.         If the same variable is declared PUBLIC in more than one module,
  102.         subsequent DEF lines will be marked '*** MULT DEF ***'.
  103.  
  104.         If a variable is declared PUBLIC in one or more modules, but no
  105.         EXTRN references were found, alint will display the message
  106.         '*** NO REF ***'.
  107.  
  108.         If an EXTRN reference was found for a variable for which there
  109.         is no PUBLIC declaration, alint will display the message '*** NO
  110.         DEF ***'.  Certain definition constructs will elude alint (such
  111.         as 'buffer equ $'), so this message may sometimes be issued
  112.         erroneously.  See the 'Limits' section below.
  113.  
  114.  
  115.         Obtaining a cross-reference
  116.         ---------------------------
  117.  
  118.         Normally, alint will display information about a data item only
  119.         if it found one of the errors described above.  You can obtain a
  120.         complete PUBLIC/EXTRN cross-reference by adding a '-x' switch
  121.         when you invoke alint:
  122.  
  123.             alint -x filelist.txt
  124.  
  125.         With the -x switch, alint will display all information described
  126.         above.
  127.  
  128.  
  129.         Output Redirection
  130.         ------------------
  131.  
  132.         You can redirect alint's principal output using DOS's standard
  133.         redirection facility.  The program logo and the list of files
  134.         being processed will not appear in the output file.
  135.  
  136.         For example, this will write a complete cross-reference to the
  137.         text file 'xref.txt':
  138.  
  139.             alint -x filelist.txt > xref.txt
  140.  
  141.  
  142.         Demo files
  143.         ----------
  144.  
  145.         Alint is accompanied by three demonstration files:
  146.  
  147.                 demo.lst
  148.                 demo1.asm
  149.                 demo2.asm
  150.  
  151.         These files provide a small demo of how alint works.  DEMO1.ASM
  152.         and DEMO2.ASM are two small assembler files (dummies) that
  153.         contain a few errors.  DEMO.LST is a small text file containing
  154.         the names of the two programs; you can use this as an alint
  155.         response file.  To see the program run, just type:
  156.  
  157.             alint demo.lst
  158.  
  159.                 -or-
  160.  
  161.             alint -x demo.lst
  162.  
  163.  
  164.         Limits
  165.         ------
  166.  
  167.         All PUBLIC statements are assumed to precede the items to which
  168.         they refer.  Although this is not a MASM requirement, it
  169.         considerably simplifies alint processing, making it faster and
  170.         smaller (and eliminating the need for two passes through the
  171.         source).
  172.  
  173.         Alint is interested ONLY in:
  174.  
  175.             1. PUBLIC items that are SUBSEQUENTLY defined via one of:
  176.                 a. DB (Define Byte)
  177.                 b. DW (Define Word)
  178.                 c. DD (Define Doubleword)
  179.                 d. DQ (Define Quadword)
  180.                 e. DT (Define Ten-byte)
  181.                 f. LABEL BYTE
  182.                 g. LABEL WORD
  183.                 h. LABEL DWORD
  184.                 i. LABEL QWORD
  185.                 j. LABEL TBYTE
  186.  
  187.             2. EXTRN items with an attribute of:
  188.                 a. BYTE
  189.                 b. WORD
  190.                 c. DWORD
  191.                 d. QWORD
  192.                 e. TBYTE
  193.  
  194.         Note in particular that alint does NOT attempt to reconcile code
  195.         labels (NEAR/FAR).  The linker should do this for you.  Also,
  196.         alint does not understand data defined via constructs such as
  197.         'buffer equ $'.  This may lead to a few incorrect error
  198.         messages.
  199.  
  200.         There is a limit of 200 PUBLICs and 200 EXTRNs per source file.
  201.  
  202.         There is a limit of 100 source files.
  203.  
  204.         Source files are assumed to be syntactically correct.  Comments
  205.         are ignored (both inline ';' comments and COMMENT blocks), and
  206.         alint is case insensitive.
  207.  
  208.         All references are stored in memory, and this is a small-model
  209.         program.  There is obviously some limit to the total number of
  210.         data references that alint can handle, but I haven't run into it
  211.         yet.
  212.  
  213.  
  214.  
  215.         License/Copyright
  216.         -----------------
  217.  
  218.         ALINT is a copyrighted work.  However, the copyright owner
  219.         hereby grants you a license to: use the program on one or more
  220.         machines; make as many copies of the program and documentation
  221.         as you wish for yourself and others; and distribute the program
  222.         and documentation via electronic or other means.
  223.  
  224.         HOWEVER, YOU MAY NOT SELL THE PROGRAM OR ANY MODIFICATION OF IT,
  225.         REQUEST DONATIONS FOR DISTRIBUTION OF THE PROGRAM, OR IN ANY
  226.         OTHER WAY TRY TO MAKE MONEY FROM MY WORK.  I MEAN IT.
  227.  
  228.         A limited exception to the above is granted to RECOGNIZED
  229.         USERS' GROUPS ONLY, which are authorized to charge a reasonable
  230.         fee to cover the cost of media, postage, and handling only.
  231.  
  232.         If you do give away copies of ALINT, you MUST distribute the
  233.         program and documentation together.  This notice must not be
  234.         deleted.
  235.  
  236.         I do not warrant that ALINT does anything worthwhile or that
  237.         this document is accurate.  I am not liable for any damages of
  238.         any kind related to the use of the program.  By using the
  239.         software, you agree to this.
  240.  
  241.  
  242.                           ALINT and this document are
  243.                             Copyright  (c) 1986 by
  244.                             Christopher J. Dunford
  245.                            10057-2 Windstream Drive
  246.                             Columbia, MD 21044 USA
  247.  
  248.                              CompuServe 76703,2002
  249.